SndNewChannel

SndNewChannel
Header:	Sound.h		Carbon status:	Supported

Allocates a new sound channel.

OSErr SndNewChannel (
    SndChannelPtr *chan, 
    SInt16 synth, 
    SInt32 init, 
    SndCallBackUPP userRoutine
);

Parameter descriptions

chan: A pointer to a sound channel structure. You can pass a pointer whose value is NULL to force the Sound Manager to allocate the sound channel structure internally.
synth: The sound data type you intend to play on this channel. If you do not want to specify a specific data type, pass 0 in this parameter. You might do this if you plan to use the channel to play a single sound resource that itself specifies the sound’s data type. See “Sound Data Type Constants”.
init: The desired initialization parameters for the channel. If you cannot determine what types of sounds you will be playing on the channel, pass 0 in this parameter. Only sounds defined by wave-table data and sampled-sound data currently use the init options. You can use the Gestalt function to determine if a sound feature (such as stereo output) is supported by a particular computer.
userRoutine: A pointer to a callback function that the Sound Manager executes whenever it receives a callBackCmd command. If you pass NULL as the userRoutine parameter, then any callBackCmd commands sent to this channel are ignored. For information on the format of a callback function, see SndCallBackProcPtr.

function result: A result code.

DISCUSSION

If you use a high-level Sound Manager function to play sounds, you might be able to let the Sound Manager internally allocate a sound channel. However, to use low-level sound commands or to take full advantage of the Sound Manager’s high-level functions, you must allocate your own sound channels.

The SndNewChannel function internally allocates memory to store a queue of sound commands. If you pass a pointer to NULL as the chan parameter, the function also allocates a sound channel structure in your application’s heap and returns a pointer to that structure. If you do not pass a pointer to NULL as the chan parameter, then that parameter must contain a pointer to a sound channel structure.

If you pass a pointer to NULL as the chan parameter, then the amount of memory the SndNewChannel function allocates to store the sound commands is enough to store 128 sound commands. However, if you pass a pointer to the sound channel structure rather than a pointer to NULL, the amount of memory allocated is determined by the qLength field of the sound channel structure. Thus, if you wish to control the size of the sound queue, you must allocate your own sound channel structure. Regardless of whether you allocate your own sound channel structure, the Sound Manager allocates memory for the sound command queue internally.

To specify a sound output device other than the current sound output device, pass the value kUseOptionalOutputDevice in the synth parameter and the signature of the desired sound output device component in the init parameter.

The ability to redirect output away from the current sound output device is intended for use by specialized applications that need to use a specific sound output device. In general, your application should always send sound to the current sound output device selected by the user.

SPECIAL CONSIDERATIONS

Because the SndNewChannel function allocates memory, you should not call it at interrupt time.

VERSION NOTES

In Sound Manager versions earlier than version 3.0, only one data type can be produced at any one time. As a result, SndNewChannel may fail if you attempt to open a channel specifying a data type other than the one currently being played.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.